<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta http-equiv="content-style-type" content="text/css">
<link rel="stylesheet" type="text/css" href="style.css">
<title>DexGuard Introduction</title>
</head>
<body>

<script type="text/javascript" language="JavaScript">
<!--
if (window.self==window.top)
  document.write('<a target="_top" href="index.html#introduction.html" class="largebutton">DexGuard index</a>')
//-->
</script>
<noscript>
<a target="_top" href="index.html#introduction.html" class="largebutton">DexGuard index</a>
</noscript>

<h2>Introduction</h2>

<b>DexGuard</b> is a bytecode shrinker, optimizer, obfuscator, and converter
for Android. The shrinking step detects and removes unused classes, fields,
methods, and attributes. The optimization step analyzes and optimizes the
bytecode of the methods. The obfuscation step renames the remaining classes,
fields, and methods using short meaningless names. These first steps make the
code base smaller, more efficient, and harder to reverse-engineer. The final
conversion step translates the Java bytecode (<code>*.class</code>) to Dalvik
bytecode for Android (<code>classes.dex</code>).
<p>

<table class="diagram" align="center">

<tr>
<td rowspan="4" class="lightblock">Input code</td>
<td colspan="8" class="transparentblock"></td>
</tr>

<tr>
<td rowspan="2" class="transparentblock"></td>
<td rowspan="3" class="lightblock">Shrunk code</td>
<td colspan="6" class="transparentblock"></td>
</tr>

<tr>
<td             class="transparentblock"></td>
<td rowspan="2" class="lightblock">Optim. code</td>
<td colspan="4" class="transparentblock"></td>
</tr>

<tr>
<td             class="transparentblock">- shrink &rarr;</td>
<td             class="transparentblock">- optimize &rarr;</td>
<td             class="transparentblock">- obfuscate &rarr;</td>
<td             class="lightblock">Obfusc. code</td>
<td             class="transparentblock">- convert &rarr;</td>
<td             class="lightblock">Output code</td>
</tr>

<tr>
<td             class="darkblock">Platform libraries</td>
<td colspan="7" class="transparentblock">------------------------------- (unchanged) -------------------------------&rarr;</td>
<td             class="darkblock">Platform libraries</td>
</tr>

</table>
<p>

DexGuard first reads the <b>input code</b> (jars, aars, wars, ears, zips, apks,
or directories, containing Java class files). The input code includes any
library projects and third-party libraries. DexGuard then subsequently shrinks,
optimizes, obfuscates, and converts the code. You can optionally let DexGuard
perform multiple optimization passes. DexGuard packages the processed <b>output
code</b> in output archives (jars, aars, wars, ears, zips, apks, or directories,
containing Dalvik bytecode). DexGuard can optionally sign and align these
archives, removing the need for external tools. The input may contain resource
files, whose names and contents can optionally be updated to reflect the
obfuscated class names.
<p>
DexGuard requires the <b>platform libraries</b> (jars, aars, wars, ears, zips,
apks, or directories) to properly process the code. For the standard Android
platform, this is simply <code>android.jar</code>.
<p>
<img class="float" src="android_shades.png" width="64" height="64" alt="tip" />
<i>The Ant build process and the Eclipse build process of DexGuard automatically
set the proper input and the proper libraries for you. You only need to
consider them if you create your own build process.</i>
<p class="clear">

<h3>Entry points</h3>

In order to determine which code has to be preserved and which code can be
discarded or obfuscated, DexGuard has to know the <i>entry points</i> to your
code. These entry points are typically classes defining activities,
intentions, etc.
<ul>
<li>In the <b>shrinking step</b>, DexGuard starts from these seeds and
    recursively determines which classes and class members are used. All other
    classes and class members are discarded.</li>

<li>In the <b>optimization step</b>, DexGuard further optimizes the code.
    Among other optimizations, classes and methods that are not entry points
    can be made private, static, or final, unused parameters can be removed,
    and some methods may be inlined.</li>

<li>In the <b>obfuscation step</b>, DexGuard renames classes and class members
    that are not entry points. In this entire process, keeping the entry
    points ensures that they can still be accessed by their original names.</li>

<li>The <b>conversion step</b> is the only step that doesn't have to know
    the entry points.</li>
</ul>
<p>
The <a href="usage.html">Usage section</a> of this manual describes the
necessary <a href="usage.html#keepoptions"><code>-keep</code> options</a> and
the <a href="examples.html">Examples section</a> provides plenty of examples.
<p>
<img class="float" src="android_shades.png" width="64" height="64" alt="tip" />
<i>The Ant build process and the Eclipse build process of DexGuard automatically
set the most common entry points for you. You only need to consider them if
you create your own build process, or if your code uses reflection, as
discussed below.</i>
<p class="clear">

<h3>Reflection</h3>

Reflection and introspection present particular problems for any automatic
processing of code. In DexGuard, classes or class members in your code that
are created or invoked dynamically (that is, by name) have to be specified as
entry points too. For example, <code>Class.forName()</code> constructs may
refer to any class at run-time. It is generally impossible to compute which
classes have to be preserved (with their original names), since the class
names might be read from a configuration file, for instance. You therefore
have to specify them in your DexGuard configuration, with the same
simple <code>-keep</code> options.
<p>
However, DexGuard will already detect and handle the following cases for you:

<ul>
<li><code>Class.forName("SomeClass")</code></li>
<li><code>SomeClass.class</code></li>
<li><code>SomeClass.class.getField("someField")</code></li>
<li><code>SomeClass.class.getDeclaredField("someField")</code></li>
<li><code>SomeClass.class.getMethod("someMethod", null)</code></li>
<li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class,... })</code></li>
<li><code>SomeClass.class.getDeclaredMethod("someMethod", null)</code></li>
<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class,... })</code></li>
<li><code>AtomicIntegerFieldUpdater.newUpdater(SomeClass.class, "someField")</code></li>
<li><code>AtomicLongFieldUpdater.newUpdater(SomeClass.class, "someField")</code></li>
<li><code>AtomicReferenceFieldUpdater.newUpdater(SomeClass.class, SomeType.class, "someField")</code></li>
</ul>

The names of the classes and class members may of course be different, but the
constructs should be literally the same for DexGuard to recognize them. The
referenced classes and class members are preserved in the shrinking phase, and
the string arguments are properly updated in the obfuscation phase.
<p>
Furthermore, DexGuard will offer some suggestions if keeping some classes or
class members appears necessary. For example, DexGuard will note constructs
like "<code>(SomeClass)Class.forName(variable).newInstance()</code>". These
might be an indication that the class or interface <code>SomeClass</code>
and/or its implementations may need to be preserved. You can then adapt your
configuration accordingly.
<p>
For proper results, you should at least be somewhat familiar with the code
that you are processing. Obfuscating code that performs a lot of reflection
may require trial and error, especially without the necessary information
about the internals of the code.

<hr />
<address>
Copyright &copy; 2002-2014
<a target="other" href="http://www.saikoa.com/">Saikoa BVBA</a>.
</address>
</body>
</html>
